docs/setup: unify agent guidance and harden Pi/server provisioning - #61

Keep AGENTS.md lean: the deep packages.json schema (per-platform scalar-or-object
resolution, environment caveat, tag-filter internals) moves to docs/PACKAGES.md,
leaving a one-paragraph summary + a pointer. Deep reference belongs in docs/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The move (56a2e17) put TODO.md and CHANGELOG.md in docs/ alongside UNIFICATION.md.
Repoint links: root/subdir files now prefix docs/ (AGENTS.md, linux-server
README/HTTPS); docs/-internal cross-links drop the stale docs/ prefix and use
siblings or ../ (CHANGELOG/TODO/UNIFICATION, and TODO's ../linux-server/HTTPS.md).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Main edited the old monolithic CLAUDE.md (linux-pi node description);
this branch made AGENTS.md the master doc with CLAUDE.md as an import
stub. Kept the stub and applied main's two Pi edits to AGENTS.md,
with TODO.md updated to its new docs/TODO.md location.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…m the always-loaded rule

The always-loaded railguard rule and the hand-maintained known-bugs tail
in CLAUDE.md carried full detail into every prompt. Move expected-behavior
detail and the bug-bounty/false-positive log (with upstream issue links)
into an on-demand docs/RAILGUARD.md; the rule shrinks to core semantics
plus a pointer to read the doc when behavior looks wrong.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Rules point at ~/.claude/docs/RAILGUARD.md by path, so install.sh now
links docs/ alongside rules/ and validate.sh checks the link.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… 58-61)

Review 1 covers AGENTS.md/CLAUDE.md/agentic-ai on this branch (15 findings);
Review 2 covers the repo as a whole with emphasis on PRs 58-60 and this PR
(15 top findings + confirmed tail). 30 verified findings total, each with
verdict and concrete failure scenario.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The cups_default bridge subnet was Docker-assigned, so a network
recreate could hand out a different CIDR and silently break the host
cupsd.conf `Allow <cidr>` rule (and thus the HTTPS front door). Pin it
to 172.21.0.0/16 to match the allow-list in /etc/cups/cupsd.conf.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The Pi's CUPS is a family-shared USB printer: family devices print over
the LAN via Bonjour (not on the tailnet), while the operator's remote
devices use the Tailscale HTTPS sidecar. Hardening it to tailnet-only
silently blocks the family, so the policy must allow localhost + the
sidecar subnet + the home LAN, and cupsd must answer to the tailnet name
plus the LAN/Bonjour names -- without ever using `ServerAlias *` / `Allow all`.

Add setup.sh, which renders that ServerAlias/<Location /> policy into
/etc/cups/cupsd.conf from a gitignored .env (LAN subnet, hostname, tailnet
name stay out of this public repo). It is idempotent, has --dry-run,
validates with `cupsd -t`, backs up before writing, and refuses to emit
`*`/`all`. .env.example carries placeholders; README.md explains the why.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Add the main server agent's Round 1 reply to the PR #61 reply chain: fast-forward to 3ff8624 with a clean worktree, server verify 38/0, and the NUT permission false-negative resolved. AdGuard credential rotation and UPS notify delivery remain not-attempted/unconfirmed this round.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The 'Secondary Server (Pi)' card hard-coded a <pi-hostname> placeholder in its description, which rendered literally on the live dashboard. Move it to HOMEPAGE_VAR_PI_HOSTNAME (real value in the gitignored .env, placeholder in .env.example), matching how the domains are handled. The value is quoted so YAML doesn't misparse the leading {{.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Skips git-tracked paths matching its glob patterns (one per line,
# comments) so intentionally non-executable shebang scripts stop
blocking session stop.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CI shellcheck fails on the unquoted RHS, but glob matching is the whole
point of .driftcheckignore patterns.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Resolves the driftcheck.sh conflict in favor of main's version: #64
landed the global ~/.claude/hooks/driftcheck-ignore design for #56, so
this branch's per-repo .driftcheckignore variant (cf23033) is dropped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Run from git rev-parse --show-toplevel so the check covers the whole
repo and ignore patterns match repo-root-relative paths regardless of
where the session started. Restore per-repo support alongside the
global file: a .driftcheckignore at the repo root is read after
~/.claude/hooks/driftcheck-ignore, same format (#56 follow-up).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>